Using the stencil buffer to mask areas

Use the stencil buffer to control which fragments Kanzi renders. You can use the stencil buffer to mask areas in the framebuffer and then use stencil testing to discard or accept fragments depending on the mask.

To use the stencil buffer to mask 3D nodes with other 3D nodes:

1. In your project create the nodes you want to use as the mask and the nodes you want to mask out.
   For example, create a Sphere node and in front of it create Box nodes you want to mask out with the Sphere node.
   
2. Tag the nodes you want to use as the mask and the nodes you want to mask out. See Tagging a node.
   For example:
   • Tag the Sphere node with the tag Mask.
   • Tag the Box nodes with the tag Masked Out.
3. Create Tag Filter resources for the nodes you want to use as the mask and for the nodes you want to mask out. See Creating a Tag Filter.
   For example, create these Tag Filter resources:
   • Masking Nodes and in the Properties add to Excluded Tags the Masked Out tag.
     
   • Masked Out Nodes and in the Properties add to Excluded Tags the Mask tag.
   
4. In the Library > Rendering > Render Passes create a Group Render Pass and inside it create:
   • Clear Render Pass
   • Two Pipeline State Render Pass resources, and name them.
     For example, name them Stencil Write and Stencil Test.
     You use the first Pipeline State Render Pass to write the masking area to the stencil buffer, and the second to compare values in the area you want to mask out to those in the stencil buffer.
   • Inside the first Pipeline State Render Pass create a Draw Objects Render Pass and name it.
     For example, name it Draw Mask.
     You use this Draw Objects Render Pass to render the nodes you use as the mask.
   • Inside the second Pipeline State Render Pass create a Draw Objects Render Pass and name it.
     For example, name it Draw Masked Out.
     You use this Draw Objects Render Pass to render the nodes you mask out.
   
5. In the Library select the Clear Render Pass you created earlier in this procedure, in the Properties add the Clear Stencil property, and set it to 0.
   You set this property to make the Clear Render Pass clear the stencil buffer with the stencil value 0.
   
6. In the Library select the first Draw Objects Render Pass you created earlier in this procedure, in the Properties add the Object Source property, and set it to the Tag Filter which collects the nodes you want to use as the mask.
   For example, select Draw Mask and in the Properties set Object Source to Masking Nodes.
   
7. In the Library select the second Draw Objects Render Pass you created earlier in this procedure, in the Properties add the Object Source property, and set it to the Tag Filter which collects the nodes you want to mask out.
   For example, select Draw Masked Out and in the Properties set Object Source to Masked Out Nodes.
   
8. In the Library select the first Pipeline State Render Pass you created, and in the Properties add and set:
   • Stencil Test Function to Always.
     You set this property to control how the stencil test compares the stencil reference value to the value in the stencil buffer. See Stencil test functions.
     
   • Stencil Function Reference Value to 1.
     
   • Stencil Pass Depth Pass Operation to Replace.
     You set this property to replace the value in the stencil buffer with the value of the Stencil Function Reference Value property. See Stencil operations.
   • Stencil Write Enabled to enabled.
   
9. In the Library select the second Pipeline State Render Pass you created and in the Properties add and set:
   • Stencil Test Function to Equal.
     You set this property to the function you use to compare the value of the Stencil Function Reference Value property to the value in the stencil buffer. See Stencil test functions.
     
   • Stencil Function Reference Value to 0.
     You set this property to the value to which you want to compare the values in the stencil buffer. Kanzi compares the value of the Stencil Function Reference Value property to the value in the stencil buffer according to the operation set by the Stencil Test Function property.
     
   
10. In the Project select the Scene node which contains the nodes you want to render and in the Properties set the Render Pass property to the Group Render Pass you created.
    Kanzi Studio renders the Scene using the render passes you created.
    
    

Stencil test functions

Use the Stencil Test Function property to compare the Stencil Function Reference Value to the value in the stencil buffer.

You can use these operations:

You can use the Stencil Function Mask property to perform a bitwise AND operation on the Stencil Function Reference Value and the value in the stencil buffer before comparing them with the Stencil Test Function. This way you can modify only certain bits in the stencil buffer. By default, and when Stencil Function Mask is set to 255, all Stencil Test Function operations both read and write all bits in the buffers.
For example, if you set Stencil Function Mask to 2, Kanzi Studio preserves only the second bit of the stencil reference value and the stencil buffer value. This way you can use different bits of the stencil buffer to mask different elements on the screen.

Stencil operations

Use the Stencil Fail Operation, Stencil Pass Depth Fail Operation and Stencil Pass Depth Pass Operation properties to set the values in the stencil buffer depending on the results of stencil and depth test. By default Kanzi Studio keeps the current value.

You can use these operations:

See also

Rendering

Using tags

Using Tag Filter filters

Open topic with navigation